<html>
<body>

Classes for importing existing JavaScript APIs and exporting Java functions to
be used JavaScript code.

<p>
The GWT compiler can automatically generate:
<ul>
<li>Linkage to functions defined within a {@link com.google.gwt.core.client.JavaScriptObject}</li>
<li>Exports of Java functions to be made available to JavaScript callers</li>
<li>Accessors for bean-style properties</li>
</ul>
</p>
<p>
Any method defined in an interface that extends {@link com.google.gwt.jsio.client.JSWrapper} or
an abstract method in a class that implements {@link com.google.gwt.jsio.client.JSWrapper} will be acted
upon by the compiler.  The default behavior is to invoke an identically-named
method on the underlying {@link com.google.gwt.core.client.JavaScriptObject}.
This behavior may be altered by the presence of various annotations on the class
and its methods.
</p>

<p>
The parameter and return types supported by JSWrapper are:
<ul>
<li>primitive</li>
<li>boxed primitive</li>
<li>{@link java.lang.String}</li>
<li>{@link com.google.gwt.jsio.client.JSFunction}</li>
<li>{@link com.google.gwt.jsio.client.JSWrapper}</li>
<li>{@link com.google.gwt.jsio.client.JSList} having a compatible component type specified with the
<code>gwt.typeArgs</code> annotation</li>
<li>{@link com.google.gwt.core.client.JavaScriptObject} and subtypes</li>
<li>{@link com.google.gwt.jsio.client.JSOpaque} as a method parameter only.</li>
</ul>
</p>

<p>
In the general case, there may be at most one {@link com.google.gwt.jsio.client.JSWrapper} associated
with a {@link com.google.gwt.core.client.JavaScriptObject}.  This allows the
JSWrapper to maintain an object identity equivalent to that of the underlying JavaScriptObject.
This is done by adding an additional property, <code>__gwtObject</code>, to the JavaScriptObject.
</p>

<h1>Annotations</h1>
<p>
The behavior of the generated classes may be altered by the presence of
various <code>@gwt</code> annotations.
<table>
<tr>
  <th>Annotation</th>
  <th>Location</th>
  <th>Description</th>
</tr>
<tr>
  <td>gwt.beanProperties</td>
  <td>Class, Method</td>
  <td>Indicates that methods that look like bean-style property setters should
    be generated so as to read and write object properties rather than import
    functions.  This is most useful with JSON-style objects.  The setting may
    by applied on a per-method basis in an imported class and may by overridden
    on a per-method basis by <code>gwt.imported</code>.
    If the backing object does not contain data for a property accessor,
    <code>null</code>, <code>0</code>, <code>' '</code>,
    <code>false</code>, or an empty {@link com.google.gwt.jsio.client.JSList}
    will be returned.
  </td>
</tr>
<tr>
  <td>gwt.constructor</td>
  <td>Class, Method</td>
  <td>The annotation <code>gwt.constructor</code> may be applied to a class to
specify a JavaScript function to execute when constructing a JSWrapper to use
as the initial backing object. A JavaScript Date object could be created by
using the value <code>$wnd.Date</code>. If the
<code>gwt.constructor</code> annotation is applied to a method within a
JSWrapper and the method invoked, the parameters of the method will be passed
to the named global function and the resulting JavaScript object will be used
as the backing object.
  </td>
</tr>
<tr>
  <td>gwt.exported</td>
  <td>Method</td>
  <td>Individual Java functions may be exported to JavaScript callers by declaring a
    <code>gwt.exported</code> annotation on a concrete Java method within a JSWrapper.
    The Java method will be bound to a property on the backing object per the class' NamePolicy
    or a <code>gwt.fieldName</code> annotation on the method.  When applied at the class
    level to a {@link com.google.gwt.jsio.client.JSFunction}, it specifies which of the methods
    declared within to type to export as a JavaScript <code>Function</code> object.
  </td>
</tr>
<tr>
  <td>gwt.fieldName</td>
  <td>Method</td>
  <td>When implementing a bean property accessor, the default NamePolicy will be used unless
	a <code>gwt.fieldName</code> annotation appears on the property's getter or setter.  This is also
	used with imported and exported functions to specify the object property to attach to.
  </td>
</tr>
<tr>
  <td>gwt.global</td>
  <td>Class</td>
  <td>The annotation <code>gwt.global</code> is similar to
<code>gwt.constructor</code>, however it may be applied only at the class
level and the value is interpreted as a globally-accessible object name,
rather than a function.
  </td>
</tr>
<tr>
  <td>gwt.imported</td>
  <td>Method</td>
  <td>This is an override for methods within classes annotated with
    <code>gwt.beanProperties</code>.
  </td>
</tr>
<tr>
  <td>gwt.namePolicy</td>
  <td>Class</td>
  <td>Specifies the default transformation to use when converting bean property
    accessor function names to fields on the underlying JavaScriptObject.
    The valid values for the <code>namePolicy</code> are the field
	names on the {@link com.google.gwt.jsio.rebind.NamePolicy} class, or the
	name of a class that implements NamePolicy.
  </td>
</tr>
<tr>
  <td>gwt.noIdentity</td>
  <td>Class</td>
  <td>This annotation suppresses the addition of the <code>__gwtObject</code> property
  on the underlying JavaScriptObject.  The object identity of the JSWrapper will no
  longer maintain a 1:1 correspondence with the underlying JavaScriptObject.  Additionally,
  {@link com.google.gwt.jsio.client.JSWrapper#setJavaScriptObject} will no longer throw
  {@link com.google.gwt.jsio.client.MultipleWrapperException}.
  </td>
</tr>
<tr>
  <td>gwt.readOnly</td>
  <td>Class</td>
  <td>This prevents the generated JSWrapper implementation from containing any code
  that will modify the underlying JavaScriptObject.  This implies <code>gwt.noIdentity</code>.
  Invoking a bean-style getter when the underlying JavaScriptObject does not contain
  a value for the property will result in undefined behavior.
  </td>
</tr>
</table>

<h1>Examples</h1>
 
<h2>HelloJSIO</h2>

<pre>
/**
 * @gwt.beanProperties
 */
interface HelloWrapper extends JSWrapper {
  public String getHello();
}
HelloWrapper hello = (HelloWrapper)GWT.create(HelloWrapper.class);
hello.setJSONData(&quot;{hello:'Hello world'}&quot;);
Window.alert(hello.getHello());
</pre>


 
<h2>Finishing an abstract class</h2>
<pre>
/**
 * @gwt.beanProperties
 */
abstract class MixedWrapper implements JSWrapper {
  // Property accessor
  public abstract int getA();

  // Property accessor
  public abstract int getB();

  public int multiply() {
    return getA() * getB();
  }

  // This method would be imported
  public abstract int importedFunction(String s);
}

MixedWrapper wrapper = (MixedWrapper)GWT.create(MixedWrapper.class);
wrapper.setJSONData(&quot;{a:2, b:5}&quot;);
Window.alert(wrapper.multiply());
</pre>

would show you the value <code>10</code>.



</body>
</html>
